# AI 肌分析 V2.1 タスクのステータスを確認します。

AI タスクは非同期です。機能ごとに Webhook がサポートされている場合は、Webhook による完了処理を優先します。Webhook エンドポイントを設定し、Webhook 署名を検証したうえで、`success` または `error` の通知が来たら、受け取った `task_id` を使ってタスクの結果を照会します。設定と検証の詳細は [Webhook 統合ガイド](../develop/webhook.md) を参照してください。
Webhook がサポートされていない場合、または統合に使えない場合は、ポーリングを実装します。AI タスクを送信した後、一定の間隔（例：10 秒ごと）でステータスエンドポイントをポーリングし、`success` または `error` になるまで待ちます。

Endpoint: GET /s2s/v2.1/task/skin-analysis/{task_id}
Security: BearerAuthenticationV2

## Security:

  - `BearerAuthenticationV2` (unknown)
    http bearer

## Path parameters:

  - `task_id` (string, required)
    確認するタスクの ID

## Response 200:

  - `200` (unknown)
    AI 肌分析タスクステータスの確認に成功しました

## Response 200 fields (application/json):

  - `status` (integer)
    レスポンスステータス
    Example: 200

  - `data` (object)

  - `data.task_status` (string)
    このタスクのステータス
    Enum: "running", "success", "error"

  - `data.error` (string)
    エラー：
- `error_exceed_max_image_size`  - 入力画像サイズが最大制限を超えています
- `exceed_max_filesize` - 入力ファイルサイズが最大制限を超えています
- `invalid_parameter` - 無効なパラメータ値
- `error_download_image` - ソース画像のダウンロードエラー
- `error_download_mask` - マスク画像のダウンロードエラー
- `error_decode_image` - ソース画像のデコードエラー
- `error_decode_mask` - マスク画像のデコードエラー
- `error_nsfw_content_detected` - ソース画像で NSFW コンテンツが検出されました
- `error_no_face` - ソース画像で顔が検出されませんでした
- `error_pose` - ソース画像でポーズの検出に失敗しました
- `error_face_parsing` - ソース画像での顔セグメンテーションに失敗しました
- `error_inference` - 推論パイプラインエラー
- `exceed_nsfw_retry_limits` - NSFW 画像の生成を避けるための再試行制限を超えました
- `error_upload` - 結果画像のアップロードエラー
- `unknown_internal_error` - その他
    Enum: "error_exceed_max_image_size", "exceed_max_filesize", "invalid_parameter", "error_download_image", "error_download_mask", "error_decode_image", "error_decode_mask", "error_nsfw_content_detected", "error_no_face", "error_pose", "error_face_parsing", "error_inference", "exceed_nsfw_retry_limits", "error_upload", "unknown_internal_error"

  - `data.error_message` (string)
    エラーの詳細説明

  - `data.results` (any)

  - `data.results.url` (string, required)
    この結果をダウンロードするための URL。有効期間は 2 時間です。返される ZIP ファイルには、すべての検出結果のスコアを含む `score_info.json` ファイルと、すべての検出結果の画像が含まれる `skinanalysisResult` フォルダが入っています。`format` が `zip` の場合のみ利用可能です。
    Example: https://example.com/sample-result-url

  - `data.results.output` (array, required)
    JSON 形式でレスポンスボディに直接返される分析結果。`format` が `json` の場合のみ利用可能です。

  - `data.results.output.type` (string)
    AI 肌分析のアクション
    Example: hd_skin_type

  - `data.results.output.region` (string)
    分析が集中する顔の領域
    Example: whole

  - `data.results.output.raw_score` (number)
    1 から 100 の範囲の浮動小数点値。`raw_score` は AI モデルによって直接予測されたスコアを指します
    Example: 98.5

  - `data.results.output.ui_score` (integer)
    1 から 100 の範囲の整数。`ui_score` は `raw_score` に基づいて調整されたスコアです
    Example: 97

  - `data.results.output.score` (number)
    一般的な肌状態を表す 1 から 100 の間の浮動小数点値。
    Example: 97.66

  - `data.results.output.mask_urls` (array)
    分析中に生成されたマスク画像またはリサイズ画像の URL

## Response 400:

  - `400` (unknown)
    無効なタスク ID

## Response 400 fields (application/json):

  - `status` (integer)
    レスポンスステータス
    Example: 400

  - `error` (string)
    Example: Invalid task ID

## Response 401:

  - `401` (unknown)
    無効または欠落している API キー

## Response 401 fields (application/json):

  - `status` (integer)
    レスポンスステータス
    Example: 401

  - `error` (string)
    Example: Invalid API key

## Response 500:

  - `500` (unknown)
    タスク実行タイムアウト

## Response 500 fields (application/json):

  - `status` (integer)
    レスポンスステータス
    Example: 500

  - `error` (string)
    Example: Task execution timed out

## Response 200 examples:

  - `format=zip の場合のレスポンス（成功）` (unknown)
    タスクが正常に完了しました。結果は ZIP ファイルとしてパッケージ化されています。

  - `format=json の場合のレスポンス（成功）` (unknown)
    タスクが正常に完了しました。結果は詳細なスコアと画像 URL を含む JSON として直接返されます。